"""
插件抽象基类
所有插件必须继承此类并实现核心方法
"""

from abc import ABC, abstractmethod
from typing import Any, Optional


class PluginBase(ABC):
    """
    插件抽象基类
    
    所有插件必须继承此类并实现以下核心方法：
    - on_load(ctx): 插件加载时调用
    - on_unload(): 插件卸载时调用
    - run(*args, **kwargs): 插件主要功能入口
    """
    
    def __init__(self) -> None:
        self.name: str = self.__class__.__name__
        self.version: str = "1.0.0"
        self.author: str = "Unknown"
        self.description: str = ""
        self.enabled: bool = False
        self._context: Optional[Any] = None
    
    @abstractmethod
    def on_load(self, context: Any) -> None:
        """
        插件加载时调用
        
        Args:
            context: API上下文对象，包含宿主提供的能力（日志、配置、数据库等）
        """
        pass
    
    @abstractmethod
    def on_unload(self) -> None:
        """
        插件卸载时调用
        清理资源、保存状态等
        """
        pass
    
    @abstractmethod
    def run(self, *args: Any, **kwargs: Any) -> Any:
        """
        插件主要功能入口
        
        Args:
            *args: 位置参数
            **kwargs: 关键字参数
            
        Returns:
            执行结果
        """
        pass
    
    def get_metadata(self) -> dict[str, Any]:
        """
        获取插件元数据
        
        Returns:
            包含插件信息的字典
        """
        return {
            'name': self.name,
            'version': self.version,
            'author': self.author,
            'description': self.description,
            'enabled': self.enabled,
        }
    
    def set_context(self, context: Any) -> None:
        """设置API上下文"""
        self._context = context
    
    def get_context(self) -> Any:
        """获取API上下文"""
        return self._context
    
    def __repr__(self) -> str:
        return f"<Plugin {self.name} v{self.version}>"
